React useFormStatus: Form Durum Yönetimi için Kapsamlı Bir Rehber

React 18'de tanıtılan useFormStatus hook'u, React Sunucu Bileşenleri (React Server Components) içindeki formların gönderim durumunu yönetmek için güçlü ve verimli bir yol sunar. Bu hook, özellikle sunucu eylemleriyle (server actions) çalışmak üzere tasarlanmıştır ve form gönderimlerini doğrudan sunucuda işlemek için sorunsuz bir entegrasyon sunar. Bir form gönderiminin durumunu izleme sürecini basitleştirir ve formun beklemede olup olmadığı, başarılı olup olmadığı veya bir hatayla karşılaşıp karşılaşmadığı gibi değerli bilgiler sağlar. Bu rehber, useFormStatus'un yeteneklerini, faydalarını ve çeşitli senaryolardaki kullanımını gösteren pratik örnekleri incelemektedir.

Sunucu Eylemlerini ve useFormStatus'u Anlamak

useFormStatus'a dalmadan önce, React Sunucu Bileşenlerini ve Sunucu Eylemlerini anlamak çok önemlidir. Sunucu Eylemleri, sunucuda çalışan ve React bileşenlerinizden doğrudan erişilebilen işlevler tanımlamanıza olanak tanır. Bu, ayrı bir API uç noktasına ihtiyaç duymadan form gönderimlerini, veri alımını ve diğer sunucu tarafı işlemleri gerçekleştirmenizi sağlar.

useFormStatus hook'u daha sonra form gönderimleri tarafından tetiklenen bu Sunucu Eylemlerinin yürütülmesine ilişkin bilgiler sağlar.

useFormStatus Nedir?

useFormStatus, en son form gönderiminin durumu hakkında bilgi içeren bir nesne döndüren bir React hook'udur. Bu bilgiler şunları içerir:

• pending: Formun o anda gönderilip gönderilmediğini belirten bir boole değeri.
• data: Gönderimle ilişkili FormData nesnesi.
• method: Gönderim için kullanılan HTTP metodu (genellikle 'POST').
• action: Tetiklenen Sunucu Eylemi (Server Action) işlevi.

useFormStatus Kullanmanın Faydaları

useFormStatus'tan yararlanmak birkaç önemli avantaj sunar:

• Basitleştirilmiş Durum Yönetimi: Form gönderim durumunu izlemek için manuel durum yönetimi ihtiyacını ortadan kaldırır. Hook, gönderim ilerledikçe otomatik olarak güncellenir.
• İyileştirilmiş Kullanıcı Deneyimi: Form işlenirken yükleme göstergeleri görüntülemek veya hata durumunda hata mesajları göstermek gibi kullanıcılara gerçek zamanlı geri bildirim sağlar.
• Temiz Kod: Form gönderim mantığını bileşen render etme işleminden ayırarak daha bildirimsel ve sürdürülebilir bir kod tabanını teşvik eder.
• Sunucu Eylemleri ile Sorunsuz Entegrasyon: Sunucu Eylemleri ile mükemmel bir şekilde çalışmak üzere tasarlanmıştır, bu da form gönderimlerini doğrudan sunucuda işlemeyi kolaylaştırır.

useFormStatus'un Pratik Örnekleri

useFormStatus'un farklı senaryolardaki kullanımını göstermek için birkaç pratik örneği inceleyelim.

Yükleme Göstergeli Temel Form Gönderimi

Bu örnek, form gönderilirken görüntülenen bir yükleme göstergesine sahip basit bir formu göstermektedir.

Sunucu Eylemi (actions.js):

'use server'

export async function submitForm(formData) {
  // Yükleme durumunu göstermek için bir gecikmeyi simüle et
  await new Promise(resolve => setTimeout(resolve, 2000));

  const name = formData.get('name');
  console.log('Form şu isimle gönderildi:', name);
  return { message: `Form şu isimle başarıyla gönderildi: ${name}` };
}

React Bileşeni (FormComponent.jsx):

'use client'

import { useFormStatus } from 'react-dom'
import { submitForm } from './actions'

function FormComponent() {
  const { pending } = useFormStatus()

  return (
    

      İsim:
      
      
        {pending ? 'Gönderiliyor...' : 'Gönder'}
      
    
  )
}

export default FormComponent

Bu örnekte, useFormStatus'tan gelen pending özelliği, form gönderilirken giriş alanını ve düğmeyi devre dışı bırakmak ve "Gönderiliyor..." mesajını görüntülemek için kullanılır.

Başarı ve Hata Durumlarını Yönetme

Bu örnek, form gönderiminden sonra başarı ve hata durumlarının nasıl yönetileceğini gösterir.

Sunucu Eylemi (actions.js):

'use server'

export async function submitForm(formData) {
  // Bir gecikmeyi simüle et
  await new Promise(resolve => setTimeout(resolve, 2000));

  const name = formData.get('name');

  if (!name) {
    throw new Error('İsim gereklidir');
  }

  console.log('Form şu isimle gönderildi:', name);
  return { message: `Form şu isimle başarıyla gönderildi: ${name}` };
}

React Bileşeni (FormComponent.jsx):

'use client'

import { useFormStatus } from 'react-dom'
import { submitForm } from './actions'
import { useState } from 'react'

function FormComponent() {
  const { pending } = useFormStatus()
  const [message, setMessage] = useState(null);
  const [error, setError] = useState(null);

  async function handleSubmit(formData) {
    try {
      const result = await submitForm(formData);
      setMessage(result.message);
      setError(null);
    } catch (e) {
      setError(e.message);
      setMessage(null);
    }
  }

  return (
    

      İsim:
      
      
        {pending ? 'Gönderiliyor...' : 'Gönder'}
      
      {pending && 
Gönderiliyor...
}
      {message && 
{message}
}
      {error && 
Hata: {error}
}
    
  )
}

export default FormComponent

Bu örnekte, handleSubmit işlevinde bir try/catch bloğu kullanılır. Eğer Sunucu Eylemi bir hata fırlatırsa, bu yakalanır ve kullanıcıya gösterilir. Başarılı gönderim üzerine bir başarı mesajı görüntülenir.

Karmaşık Veriler için FormData Kullanımı

useFormStatus, FormData ile sorunsuz bir şekilde çalışır ve karmaşık veri yapılarını kolaylıkla yönetmenizi sağlar. İşte dosya yüklemeyi gösteren bir örnek.

Sunucu Eylemi (actions.js):

'use server'

export async function uploadFile(formData) {
  // Dosya işlemeyi simüle et
  await new Promise(resolve => setTimeout(resolve, 2000));

  const file = formData.get('file');

  if (!file) {
    throw new Error('Dosya yüklenmedi');
  }

  console.log('Dosya yüklendi:', file.name);
  return { message: `Dosya başarıyla yüklendi: ${file.name}` };
}

React Bileşeni (FormComponent.jsx):

'use client'

import { useFormStatus } from 'react-dom'
import { uploadFile } from './actions'
import { useState } from 'react'

function FormComponent() {
  const { pending } = useFormStatus()
  const [message, setMessage] = useState(null);
  const [error, setError] = useState(null);

  async function handleSubmit(formData) {
    try {
      const result = await uploadFile(formData);
      setMessage(result.message);
      setError(null);
    } catch (e) {
      setError(e.message);
      setMessage(null);
    }
  }

  return (
    

      Dosya Yükle:
      
      
        {pending ? 'Yükleniyor...' : 'Yükle'}
      
      {pending && 
Yükleniyor...
}
      {message && 
{message}
}
      {error && 
Hata: {error}
}
    
  )
}

export default FormComponent

Bu örnek, FormData kullanarak dosya yüklemelerinin nasıl yönetileceğini gösterir. Sunucu eylemi, dosyayı FormData nesnesinden alır ve işler. useFormStatus hook'u, dosya yüklenirken yükleme durumunu yönetir.

useFormStatus Kullanımı için En İyi Uygulamalar

useFormStatus'un faydalarını en üst düzeye çıkarmak için şu en iyi uygulamaları göz önünde bulundurun:

• Net Kullanıcı Geri Bildirimi Sağlayın: Bilgilendirici yükleme göstergeleri görüntülemek ve birden fazla gönderimi önlemek için form elemanlarını devre dışı bırakmak için pending durumunu kullanın.
• Hataları Zarif Bir Şekilde Yönetin: Sunucu Eylemlerinizdeki istisnaları yakalamak ve kullanıcı dostu hata mesajları görüntülemek için hata yönetimi uygulayın.
• Verileri Sunucuda Doğrulayın: Veri bütünlüğünü ve güvenliğini sağlamak için sunucu tarafı doğrulama yapın.
• Sunucu Eylemlerini Kısa Tutun: Performansı ve sürdürülebilirliği artırmak için Sunucu Eylemlerini belirli görevlere odaklayın.
• Erişilebilirliği Göz Önünde Bulundurun: Uygun etiketler, ARIA nitelikleri ve klavye navigasyon desteği sağlayarak formlarınızın erişilebilir olduğundan emin olun.

İleri Düzey Kullanım Senaryoları

Temel örneklerin ötesinde, useFormStatus daha karmaşık senaryolarda kullanılabilir:

• Aşamalı Geliştirme (Progressive Enhancement): JavaScript'i devre dışı bırakmış kullanıcılar için temel bir deneyim ve JavaScript'i etkinleştirmiş olanlar için daha zengin bir deneyim sunarak formlarınızı aşamalı olarak geliştirmek için Sunucu Eylemlerini ve useFormStatus'u kullanın.
• İyimser Güncellemeler (Optimistic Updates): Form gönderildikten hemen sonra, gönderimin başarılı olacağını varsayarak kullanıcı arayüzünü güncelleyerek iyimser güncellemeler uygulayın. Gönderim başarısız olursa güncellemeyi geri alın.
• Form Kütüphaneleri Entegrasyonu: Form durumunu ve doğrulamayı yönetmek için useFormStatus'u Formik veya React Hook Form gibi popüler form kütüphaneleriyle entegre edin. Bu kütüphanelerin genellikle kendi durum yönetimleri olsa da, useFormStatus bir sunucu eylemine son gönderim aşaması için faydalı olabilir.

Uluslararasılaştırma (i18n) için Dikkat Edilmesi Gerekenler

Küresel bir kitle için formlar oluştururken, uluslararasılaştırma (i18n) çok önemlidir. İşte useFormStatus kullanırken i18n'i nasıl göz önünde bulundurmanız gerektiği:

• Yerelleştirilmiş Hata Mesajları: Kullanıcıya gösterilen hata mesajlarının kendi tercih ettikleri dile göre yerelleştirildiğinden emin olun. Bu, hata mesajlarını çeviri dosyalarında saklayarak ve uygun çeviriyi almak için react-intl veya i18next gibi bir kütüphane kullanarak başarılabilir.
• Tarih ve Sayı Biçimlendirme: Tarih ve sayı biçimlendirmesini kullanıcının yerel ayarlarına göre yapın. Bu değerleri doğru bir şekilde biçimlendirmek için Intl.DateTimeFormat ve Intl.NumberFormat gibi kütüphaneleri kullanın.
• Sağdan Sola (RTL) Desteği: Uygulamanız sağdan sola yazılan dilleri (örneğin, Arapça, İbranice) destekliyorsa, formlarınızın RTL düzenlerine uyacak şekilde uygun şekilde stillendirildiğinden emin olun.
• Form Doğrulama: Form doğrulama kurallarını farklı yerel ayarlara göre uyarlayın. Örneğin, telefon numarası doğrulaması ülkeler arasında önemli ölçüde farklılık gösterebilir.

Yerelleştirilmiş Hata Mesajları Örneği:

// translations/tr.json
{
  "form.error.nameRequired": "Lütfen adınızı girin.",
  "form.success.submission": "Gönderiminiz için teşekkür ederiz!"
}

// react-intl kullanan bileşen
import { useIntl } from 'react-intl';

function FormComponent() {
  const intl = useIntl();
  const [error, setError] = useState(null);

  // ...

  catch (e) {
    setError(intl.formatMessage({ id: 'form.error.nameRequired' }));
  }
}

Erişilebilirlik Hususları

Erişilebilirlik, kapsayıcı web uygulamaları oluşturmanın önemli bir yönüdür. İşte useFormStatus kullanırken akılda tutulması gereken birkaç erişilebilirlik hususu:

• ARIA Nitelikleri: Yardımcı teknolojilere formun durumu hakkında bilgi sağlamak için ARIA niteliklerini kullanın. Örneğin, form beklemedeyken gönder düğmesinde aria-busy="true" kullanın.
• Etiketler: Tüm form alanlarının, <label> elemanı kullanılarak giriş elemanlarıyla ilişkilendirilmiş açık ve açıklayıcı etiketlere sahip olduğundan emin olun.
• Hata Mesajları: Hata mesajlarını, engelli kullanıcılar tarafından kolayca fark edilebilir ve anlaşılabilir bir şekilde görüntüleyin. Hata mesajlarını ekran okuyuculara duyurmak için aria-live="assertive" gibi ARIA niteliklerini kullanın.
• Klavye Navigasyonu: Kullanıcıların formu yalnızca klavye kullanarak gezebildiğinden emin olun. Elemanların odaklanma sırasını kontrol etmek için tabindex niteliğini kullanın.
• Renk Kontrastı: Formda kullanılan metin ve arka plan renklerinin, görme engelli kullanıcılar tarafından kolayca okunabilir olması için yeterli kontrasta sahip olduğundan emin olun.

useFormStatus vs. Geleneksel Durum Yönetimi

Geleneksel olarak, React geliştiricileri form gönderim durumunu bileşen durumu (useState) veya daha karmaşık durum yönetimi kütüphaneleri (örneğin, Redux, Zustand) kullanarak yönetmişlerdir. İşte bu yaklaşımların useFormStatus ile bir karşılaştırması:

Özellik	useFormStatus	useState	Harici Durum Yönetimi
Karmaşıklık	Düşük	Orta	Yüksek
Sunucu Eylemleri ile Entegrasyon	Sorunsuz	Manuel entegrasyon gerektirir	Manuel entegrasyon gerektirir
Tekrarlayan Kod (Boilerplate)	Minimum	Orta Düzey	Önemli Miktarda
Uygun Kullanım Alanları	Doğrudan Sunucu Eylemlerine gönderilen formlar	Sınırlı duruma sahip basit formlar	Bileşenler arasında paylaşılan duruma sahip karmaşık formlar

useFormStatus, formlarınız doğrudan React Sunucu Eylemleri ile etkileşime girdiğinde parlar. Tekrarlayan kodu azaltır ve süreci basitleştirir. Ancak, birden fazla bileşen arasında paylaşılan duruma sahip çok karmaşık formlar için, tam teşekküllü bir durum yönetimi kütüphanesi hala gerekli olabilir.

Yaygın Sorunları Giderme

useFormStatus kullanırken karşılaşabileceğiniz bazı yaygın sorunlar ve bunları nasıl gidereceğiniz aşağıda verilmiştir:

• useFormStatus güncellenmiyor:
  • useFormStatus'u, action prop'u bir Sunucu Eylemine ayarlanmış bir <form> elemanı içinde kullandığınızdan emin olun.
  • Sunucu Eyleminin doğru bir şekilde tanımlandığını ve dışa aktarıldığını doğrulayın.
  • Sunucu Eyleminde, başarıyla tamamlanmasını engelleyebilecek herhangi bir hata olup olmadığını kontrol edin.
• Hata mesajları görüntülenmiyor:
  • Sunucu Eyleminizde hataları doğru bir şekilde yakaladığınızdan ve bir hata mesajı döndürdüğünüzden emin olun.
  • Bileşeninizde error durumunu kullanarak hata mesajını görüntülediğinizi doğrulayın.
• Yükleme göstergesi görünmüyor:
  • Yükleme göstergesini koşullu olarak görüntülemek için useFormStatus'tan gelen pending durumunu kullandığınızdan emin olun.
  • Sunucu Eyleminin gerçekten tamamlanması için bir süre geçtiğini kontrol edin (örneğin, bir gecikme simüle ederek).

Sonuç

useFormStatus, Sunucu Bileşenlerini kullanan React uygulamalarında form gönderim durumunu yönetmek için temiz ve verimli bir yol sunar. Bu hook'tan yararlanarak kodunuzu basitleştirebilir, kullanıcı deneyimini iyileştirebilir ve Sunucu Eylemleri ile sorunsuz bir şekilde entegre olabilirsiniz. Bu rehber, useFormStatus'un temellerini ele almış, pratik örnekler sunmuş ve etkili bir şekilde kullanmak için en iyi uygulamaları tartışmıştır. useFormStatus'u React projelerinize dahil ederek, form yönetimini kolaylaştırabilir ve küresel bir kitle için daha sağlam ve kullanıcı dostu uygulamalar oluşturabilirsiniz.